<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This file documents the use of the GNU compilers.

Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Instrumentation Options (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Instrumentation Options (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Instrumentation Options (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Invoking-GCC.html" rel="up" title="Invoking GCC">
<link href="Preprocessor-Options.html" rel="next" title="Preprocessor Options">
<link href="Optimize-Options.html" rel="prev" title="Optimize Options">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
ul.mark-bullet {list-style-type: disc}
-->
</style>


</head>

<body lang="en_US">
<div class="section-level-extent" id="Instrumentation-Options">
<div class="nav-panel">
<p>
Next: <a href="Preprocessor-Options.html" accesskey="n" rel="next">Options Controlling the Preprocessor</a>, Previous: <a href="Optimize-Options.html" accesskey="p" rel="prev">Options That Control Optimization</a>, Up: <a href="Invoking-GCC.html" accesskey="u" rel="up">GCC Command Options</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Program-Instrumentation-Options"><span>3.12 Program Instrumentation Options<a class="copiable-link" href="#Program-Instrumentation-Options"> &para;</a></span></h3>
<a class="index-entry-id" id="index-instrumentation-options"></a>
<a class="index-entry-id" id="index-program-instrumentation-options"></a>
<a class="index-entry-id" id="index-run_002dtime-error-checking-options"></a>
<a class="index-entry-id" id="index-profiling-options"></a>
<a class="index-entry-id" id="index-options_002c-program-instrumentation"></a>
<a class="index-entry-id" id="index-options_002c-run_002dtime-error-checking"></a>
<a class="index-entry-id" id="index-options_002c-profiling"></a>

<p>GCC supports a number of command-line options that control adding
run-time instrumentation to the code it normally generates.  
For example, one purpose of instrumentation is collect profiling
statistics for use in finding program hot spots, code coverage
analysis, or profile-guided optimizations.
Another class of program instrumentation is adding run-time checking 
to detect programming errors like invalid pointer
dereferences or out-of-bounds array accesses, as well as deliberately
hostile attacks such as stack smashing or C++ vtable hijacking.
There is also a general hook which can be used to implement other
forms of tracing or function-level instrumentation for debug or
program analysis purposes.
</p>
<dl class="table">
<dt><a class="index-entry-id" id="index-gprof"></a>
<a class="index-entry-id" id="index-p"></a>
<a class="index-entry-id" id="index-pg"></a>
<a id="index-prof"></a><span><code class="code">-p</code><a class="copiable-link" href="#index-prof"> &para;</a></span></dt>
<dt><code class="code">-pg</code></dt>
<dd><p>Generate extra code to write profile information suitable for the
analysis program <code class="command">prof</code> (for <samp class="option">-p</samp>) or <code class="command">gprof</code>
(for <samp class="option">-pg</samp>).  You must use this option when compiling
the source files you want data about, and you must also use it when
linking.
</p>
<p>You can use the function attribute <code class="code">no_instrument_function</code> to
suppress profiling of individual functions when compiling with these options.
See <a class="xref" href="Common-Function-Attributes.html">Common Function Attributes</a>.
</p>
</dd>
<dt><a id="index-fprofile_002darcs"></a><span><code class="code">-fprofile-arcs</code><a class="copiable-link" href="#index-fprofile_002darcs"> &para;</a></span></dt>
<dd><p>Add code so that program flow <em class="dfn">arcs</em> are instrumented.  During
execution the program records how many times each branch and call is
executed and how many times it is taken or returns.  On targets that support
constructors with priority support, profiling properly handles constructors,
destructors and C++ constructors (and destructors) of classes which are used
as a type of a global variable.
</p>
<p>When the compiled
program exits it saves this data to a file called
<samp class="file"><var class="var">auxname</var>.gcda</samp> for each source file.  The data may be used for
profile-directed optimizations (<samp class="option">-fbranch-probabilities</samp>), or for
test coverage analysis (<samp class="option">-ftest-coverage</samp>).  Each object file&rsquo;s
<var class="var">auxname</var> is generated from the name of the output file, if
explicitly specified and it is not the final executable, otherwise it is
the basename of the source file.  In both cases any suffix is removed
(e.g. <samp class="file">foo.gcda</samp> for input file <samp class="file">dir/foo.c</samp>, or
<samp class="file">dir/foo.gcda</samp> for output file specified as <samp class="option">-o dir/foo.o</samp>).
</p>
<p>Note that if a command line directly links source files, the corresponding
<var class="var">.gcda</var> files will be prefixed with the unsuffixed name of the output file.
E.g. <code class="code">gcc a.c b.c -o binary</code> would generate <samp class="file">binary-a.gcda</samp> and
<samp class="file">binary-b.gcda</samp> files.
</p>
<p>See <a class="xref" href="Cross_002dprofiling.html">Data File Relocation to Support Cross-Profiling</a>.
</p>
</dd>
<dt><a class="index-entry-id" id="index-coverage"></a>
<a id="index-gcov"></a><span><code class="code">--coverage</code><a class="copiable-link" href="#index-gcov"> &para;</a></span></dt>
<dd>
<p>This option is used to compile and link code instrumented for coverage
analysis.  The option is a synonym for <samp class="option">-fprofile-arcs</samp>
<samp class="option">-ftest-coverage</samp> (when compiling) and <samp class="option">-lgcov</samp> (when
linking).  See the documentation for those options for more details.
</p>
<ul class="itemize mark-bullet">
<li>Compile the source files with <samp class="option">-fprofile-arcs</samp> plus optimization
and code generation options.  For test coverage analysis, use the
additional <samp class="option">-ftest-coverage</samp> option.  You do not need to profile
every source file in a program.

</li><li>Compile the source files additionally with <samp class="option">-fprofile-abs-path</samp>
to create absolute path names in the <samp class="file">.gcno</samp> files.  This allows
<code class="command">gcov</code> to find the correct sources in projects where compilations
occur with different working directories.

</li><li>Link your object files with <samp class="option">-lgcov</samp> or <samp class="option">-fprofile-arcs</samp>
(the latter implies the former).

</li><li>Run the program on a representative workload to generate the arc profile
information.  This may be repeated any number of times.  You can run
concurrent instances of your program, and provided that the file system
supports locking, the data files will be correctly updated.  Unless
a strict ISO C dialect option is in effect, <code class="code">fork</code> calls are
detected and correctly handled without double counting.

<p>Moreover, an object file can be recompiled multiple times
and the corresponding <samp class="file">.gcda</samp> file merges as long as
the source file and the compiler options are unchanged.
</p>
</li><li>For profile-directed optimizations, compile the source files again with
the same optimization and code generation options plus
<samp class="option">-fbranch-probabilities</samp> (see <a class="pxref" href="Optimize-Options.html">Options that
Control Optimization</a>).

</li><li>For test coverage analysis, use <code class="command">gcov</code> to produce human readable
information from the <samp class="file">.gcno</samp> and <samp class="file">.gcda</samp> files.  Refer to the
<code class="command">gcov</code> documentation for further information.

</li></ul>

<p>With <samp class="option">-fprofile-arcs</samp>, for each function of your program GCC
creates a program flow graph, then finds a spanning tree for the graph.
Only arcs that are not on the spanning tree have to be instrumented: the
compiler adds code to count the number of times that these arcs are
executed.  When an arc is the only exit or only entrance to a block, the
instrumentation code can be added to the block; otherwise, a new basic
block must be created to hold the instrumentation code.
</p>
</dd>
<dt><a id="index-ftest_002dcoverage"></a><span><code class="code">-ftest-coverage</code><a class="copiable-link" href="#index-ftest_002dcoverage"> &para;</a></span></dt>
<dd><p>Produce a notes file that the <code class="command">gcov</code> code-coverage utility
(see <a class="pxref" href="Gcov.html"><code class="command">gcov</code>&mdash;a Test Coverage Program</a>) can use to
show program coverage.  Each source file&rsquo;s note file is called
<samp class="file"><var class="var">auxname</var>.gcno</samp>.  Refer to the <samp class="option">-fprofile-arcs</samp> option
above for a description of <var class="var">auxname</var> and instructions on how to
generate test coverage data.  Coverage data matches the source files
more closely if you do not optimize.
</p>
</dd>
<dt><a id="index-fprofile_002dabs_002dpath"></a><span><code class="code">-fprofile-abs-path</code><a class="copiable-link" href="#index-fprofile_002dabs_002dpath"> &para;</a></span></dt>
<dd><p>Automatically convert relative source file names to absolute path names
in the <samp class="file">.gcno</samp> files.  This allows <code class="command">gcov</code> to find the correct
sources in projects where compilations occur with different working
directories.
</p>
</dd>
<dt><a id="index-fprofile_002ddir"></a><span><code class="code">-fprofile-dir=<var class="var">path</var></code><a class="copiable-link" href="#index-fprofile_002ddir"> &para;</a></span></dt>
<dd>
<p>Set the directory to search for the profile data files in to <var class="var">path</var>.
This option affects only the profile data generated by
<samp class="option">-fprofile-generate</samp>, <samp class="option">-ftest-coverage</samp>, <samp class="option">-fprofile-arcs</samp>
and used by <samp class="option">-fprofile-use</samp> and <samp class="option">-fbranch-probabilities</samp>
and its related options.  Both absolute and relative paths can be used.
By default, GCC uses the current directory as <var class="var">path</var>, thus the
profile data file appears in the same directory as the object file.
In order to prevent the file name clashing, if the object file name is
not an absolute path, we mangle the absolute path of the
<samp class="file"><var class="var">sourcename</var>.gcda</samp> file and use it as the file name of a
<samp class="file">.gcda</samp> file.  See details about the file naming in <samp class="option">-fprofile-arcs</samp>.
See similar option <samp class="option">-fprofile-note</samp>.
</p>
<p>When an executable is run in a massive parallel environment, it is recommended
to save profile to different folders.  That can be done with variables
in <var class="var">path</var> that are exported during run-time:
</p>
<dl class="table">
<dt><code class="code">%p</code></dt>
<dd><p>process ID.
</p>
</dd>
<dt><code class="code">%q{VAR}</code></dt>
<dd><p>value of environment variable <var class="var">VAR</var>
</p>
</dd>
</dl>

</dd>
<dt><a id="index-fprofile_002dgenerate"></a><span><code class="code">-fprofile-generate</code><a class="copiable-link" href="#index-fprofile_002dgenerate"> &para;</a></span></dt>
<dt><code class="code">-fprofile-generate=<var class="var">path</var></code></dt>
<dd>
<p>Enable options usually used for instrumenting application to produce
profile useful for later recompilation with profile feedback based
optimization.  You must use <samp class="option">-fprofile-generate</samp> both when
compiling and when linking your program.
</p>
<p>The following options are enabled:
<samp class="option">-fprofile-arcs</samp>, <samp class="option">-fprofile-values</samp>,
<samp class="option">-finline-functions</samp>, and <samp class="option">-fipa-bit-cp</samp>.
</p>
<p>If <var class="var">path</var> is specified, GCC looks at the <var class="var">path</var> to find
the profile feedback data files. See <samp class="option">-fprofile-dir</samp>.
</p>
<p>To optimize the program based on the collected profile information, use
<samp class="option">-fprofile-use</samp>.  See <a class="xref" href="Optimize-Options.html">Options That Control Optimization</a>, for more information.
</p>
</dd>
<dt><a id="index-fprofile_002dinfo_002dsection"></a><span><code class="code">-fprofile-info-section</code><a class="copiable-link" href="#index-fprofile_002dinfo_002dsection"> &para;</a></span></dt>
<dt><code class="code">-fprofile-info-section=<var class="var">name</var></code></dt>
<dd>
<p>Register the profile information in the specified section instead of using a
constructor/destructor.  The section name is <var class="var">name</var> if it is specified,
otherwise the section name defaults to <code class="code">.gcov_info</code>.  A pointer to the
profile information generated by <samp class="option">-fprofile-arcs</samp> is placed in the
specified section for each translation unit.  This option disables the profile
information registration through a constructor and it disables the profile
information processing through a destructor.  This option is not intended to be
used in hosted environments such as GNU/Linux.  It targets freestanding
environments (for example embedded systems) with limited resources which do not
support constructors/destructors or the C library file I/O.
</p>
<p>The linker could collect the input sections in a continuous memory block and
define start and end symbols.  A GNU linker script example which defines a
linker output section follows:
</p>
<div class="example smallexample">
<pre class="example-preformatted">  .gcov_info      :
  {
    PROVIDE (__gcov_info_start = .);
    KEEP (*(.gcov_info))
    PROVIDE (__gcov_info_end = .);
  }
</pre></div>

<p>The program could dump the profiling information registered in this linker set
for example like this:
</p>
<div class="example smallexample">
<pre class="example-preformatted">#include &lt;gcov.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;

extern const struct gcov_info *const __gcov_info_start[];
extern const struct gcov_info *const __gcov_info_end[];

static void
dump (const void *d, unsigned n, void *arg)
{
  const unsigned char *c = d;

  for (unsigned i = 0; i &lt; n; ++i)
    printf (&quot;%02x&quot;, c[i]);
}

static void
filename (const char *f, void *arg)
{
  __gcov_filename_to_gcfn (f, dump, arg );
}

static void *
allocate (unsigned length, void *arg)
{
  return malloc (length);
}

static void
dump_gcov_info (void)
{
  const struct gcov_info *const *info = __gcov_info_start;
  const struct gcov_info *const *end = __gcov_info_end;

  /* Obfuscate variable to prevent compiler optimizations.  */
  __asm__ (&quot;&quot; : &quot;+r&quot; (info));

  while (info != end)
  {
    void *arg = NULL;
    __gcov_info_to_gcda (*info, filename, dump, allocate, arg);
    putchar ('\n');
    ++info;
  }
}

int
main (void)
{
  dump_gcov_info ();
  return 0;
}
</pre></div>

<p>The <code class="command">merge-stream</code> subcommand of <code class="command">gcov-tool</code> may be used to
deserialize the data stream generated by the <code class="code">__gcov_filename_to_gcfn</code> and
<code class="code">__gcov_info_to_gcda</code> functions and merge the profile information into
<samp class="file">.gcda</samp> files on the host filesystem.
</p>
</dd>
<dt><a id="index-fprofile_002dnote"></a><span><code class="code">-fprofile-note=<var class="var">path</var></code><a class="copiable-link" href="#index-fprofile_002dnote"> &para;</a></span></dt>
<dd>
<p>If <var class="var">path</var> is specified, GCC saves <samp class="file">.gcno</samp> file into <var class="var">path</var>
location.  If you combine the option with multiple source files,
the <samp class="file">.gcno</samp> file will be overwritten.
</p>
</dd>
<dt><a id="index-fprofile_002dprefix_002dpath"></a><span><code class="code">-fprofile-prefix-path=<var class="var">path</var></code><a class="copiable-link" href="#index-fprofile_002dprefix_002dpath"> &para;</a></span></dt>
<dd>
<p>This option can be used in combination with
<samp class="option">profile-generate=</samp><var class="var">profile_dir</var> and
<samp class="option">profile-use=</samp><var class="var">profile_dir</var> to inform GCC where is the base
directory of built source tree.  By default <var class="var">profile_dir</var> will contain
files with mangled absolute paths of all object files in the built project.
This is not desirable when directory used to build the instrumented binary
differs from the directory used to build the binary optimized with profile
feedback because the profile data will not be found during the optimized build.
In such setups <samp class="option">-fprofile-prefix-path=</samp><var class="var">path</var> with <var class="var">path</var>
pointing to the base directory of the build can be used to strip the irrelevant
part of the path and keep all file names relative to the main build directory.
</p>
</dd>
<dt><a id="index-fprofile_002dprefix_002dmap"></a><span><code class="code">-fprofile-prefix-map=<var class="var">old</var>=<var class="var">new</var></code><a class="copiable-link" href="#index-fprofile_002dprefix_002dmap"> &para;</a></span></dt>
<dd><p>When compiling files residing in directory <samp class="file"><var class="var">old</var></samp>, record
profiling information (with <samp class="option">--coverage</samp>)
describing them as if the files resided in
directory <samp class="file"><var class="var">new</var></samp> instead.
See also <samp class="option">-ffile-prefix-map</samp> and <samp class="option">-fcanon-prefix-map</samp>.
</p>
</dd>
<dt><a id="index-fprofile_002dupdate"></a><span><code class="code">-fprofile-update=<var class="var">method</var></code><a class="copiable-link" href="#index-fprofile_002dupdate"> &para;</a></span></dt>
<dd>
<p>Alter the update method for an application instrumented for profile
feedback based optimization.  The <var class="var">method</var> argument should be one of
&lsquo;<samp class="samp">single</samp>&rsquo;, &lsquo;<samp class="samp">atomic</samp>&rsquo; or &lsquo;<samp class="samp">prefer-atomic</samp>&rsquo;.
The first one is useful for single-threaded applications,
while the second one prevents profile corruption by emitting thread-safe code.
</p>
<p><strong class="strong">Warning:</strong> When an application does not properly join all threads
(or creates an detached thread), a profile file can be still corrupted.
</p>
<p>Using &lsquo;<samp class="samp">prefer-atomic</samp>&rsquo; would be transformed either to &lsquo;<samp class="samp">atomic</samp>&rsquo;,
when supported by a target, or to &lsquo;<samp class="samp">single</samp>&rsquo; otherwise.  The GCC driver
automatically selects &lsquo;<samp class="samp">prefer-atomic</samp>&rsquo; when <samp class="option">-pthread</samp>
is present in the command line.
</p>
</dd>
<dt><a id="index-fprofile_002dfilter_002dfiles"></a><span><code class="code">-fprofile-filter-files=<var class="var">regex</var></code><a class="copiable-link" href="#index-fprofile_002dfilter_002dfiles"> &para;</a></span></dt>
<dd>
<p>Instrument only functions from files whose name matches
any of the regular expressions (separated by semi-colons).
</p>
<p>For example, <samp class="option">-fprofile-filter-files=main\.c;module.*\.c</samp> will instrument
only <samp class="file">main.c</samp> and all C files starting with &rsquo;module&rsquo;.
</p>
</dd>
<dt><a id="index-fprofile_002dexclude_002dfiles"></a><span><code class="code">-fprofile-exclude-files=<var class="var">regex</var></code><a class="copiable-link" href="#index-fprofile_002dexclude_002dfiles"> &para;</a></span></dt>
<dd>
<p>Instrument only functions from files whose name does not match
any of the regular expressions (separated by semi-colons).
</p>
<p>For example, <samp class="option">-fprofile-exclude-files=/usr/.*</samp> will prevent instrumentation
of all files that are located in the <samp class="file">/usr/</samp> folder.
</p>
</dd>
<dt><a id="index-fprofile_002dreproducible"></a><span><code class="code">-fprofile-reproducible=<span class="r">[</span>multithreaded<span class="r">|</span>parallel-runs<span class="r">|</span>serial<span class="r">]</span></code><a class="copiable-link" href="#index-fprofile_002dreproducible"> &para;</a></span></dt>
<dd><p>Control level of reproducibility of profile gathered by
<code class="code">-fprofile-generate</code>.  This makes it possible to rebuild program
with same outcome which is useful, for example, for distribution
packages.
</p>
<p>With <samp class="option">-fprofile-reproducible=serial</samp> the profile gathered by
<samp class="option">-fprofile-generate</samp> is reproducible provided the trained program
behaves the same at each invocation of the train run, it is not
multi-threaded and profile data streaming is always done in the same
order.  Note that profile streaming happens at the end of program run but
also before <code class="code">fork</code> function is invoked.
</p>
<p>Note that it is quite common that execution counts of some part of
programs depends, for example, on length of temporary file names or
memory space randomization (that may affect hash-table collision rate).
Such non-reproducible part of programs may be annotated by
<code class="code">no_instrument_function</code> function attribute. <code class="command">gcov-dump</code> with
<samp class="option">-l</samp> can be used to dump gathered data and verify that they are
indeed reproducible.
</p>
<p>With <samp class="option">-fprofile-reproducible=parallel-runs</samp> collected profile
stays reproducible regardless the order of streaming of the data into
gcda files.  This setting makes it possible to run multiple instances of
instrumented program in parallel (such as with <code class="code">make -j</code>). This
reduces quality of gathered data, in particular of indirect call
profiling.
</p>
</dd>
<dt><a id="index-fsanitize_003daddress"></a><span><code class="code">-fsanitize=address</code><a class="copiable-link" href="#index-fsanitize_003daddress"> &para;</a></span></dt>
<dd><p>Enable AddressSanitizer, a fast memory error detector.
Memory access instructions are instrumented to detect
out-of-bounds and use-after-free bugs.
The option enables <samp class="option">-fsanitize-address-use-after-scope</samp>.
See <a class="uref" href="https://github.com/google/sanitizers/wiki/AddressSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizer</a> for
more details.  The run-time behavior can be influenced using the
<code class="env">ASAN_OPTIONS</code> environment variable.  When set to <code class="code">help=1</code>,
the available options are shown at startup of the instrumented program.  See
<a class="url" href="https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags">https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags</a>
for a list of supported options.
The option cannot be combined with <samp class="option">-fsanitize=thread</samp> or
<samp class="option">-fsanitize=hwaddress</samp>.  Note that the only target
<samp class="option">-fsanitize=hwaddress</samp> is currently supported on is AArch64.
</p>
<p>To get more accurate stack traces, it is possible to use options such as
<samp class="option">-O0</samp>, <samp class="option">-O1</samp>, or <samp class="option">-Og</samp> (which, for instance, prevent
most function inlining), <samp class="option">-fno-optimize-sibling-calls</samp> (which prevents
optimizing sibling and tail recursive calls; this option is implicit for
<samp class="option">-O0</samp>, <samp class="option">-O1</samp>, or <samp class="option">-Og</samp>), or <samp class="option">-fno-ipa-icf</samp> (which
disables Identical Code Folding for functions).  Since multiple runs of the
program may yield backtraces with different addresses due to ASLR (Address
Space Layout Randomization), it may be desirable to turn ASLR off.  On Linux,
this can be achieved with &lsquo;<samp class="samp">setarch `uname -m` -R ./prog</samp>&rsquo;.
</p>
</dd>
<dt><a id="index-fsanitize_003dkernel_002daddress"></a><span><code class="code">-fsanitize=kernel-address</code><a class="copiable-link" href="#index-fsanitize_003dkernel_002daddress"> &para;</a></span></dt>
<dd><p>Enable AddressSanitizer for Linux kernel.
See <a class="uref" href="https://github.com/google/kernel-sanitizers">https://github.com/google/kernel-sanitizers</a> for more details.
</p>
</dd>
<dt><a id="index-fsanitize_003dhwaddress"></a><span><code class="code">-fsanitize=hwaddress</code><a class="copiable-link" href="#index-fsanitize_003dhwaddress"> &para;</a></span></dt>
<dd><p>Enable Hardware-assisted AddressSanitizer, which uses a hardware ability to
ignore the top byte of a pointer to allow the detection of memory errors with
a low memory overhead.
Memory access instructions are instrumented to detect out-of-bounds and
use-after-free bugs.
The option enables <samp class="option">-fsanitize-address-use-after-scope</samp>.
See
<a class="uref" href="https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html">https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html</a>
for more details.  The run-time behavior can be influenced using the
<code class="env">HWASAN_OPTIONS</code> environment variable.  When set to <code class="code">help=1</code>,
the available options are shown at startup of the instrumented program.
The option cannot be combined with <samp class="option">-fsanitize=thread</samp> or
<samp class="option">-fsanitize=address</samp>, and is currently only available on AArch64.
</p>
</dd>
<dt><a id="index-fsanitize_003dkernel_002dhwaddress"></a><span><code class="code">-fsanitize=kernel-hwaddress</code><a class="copiable-link" href="#index-fsanitize_003dkernel_002dhwaddress"> &para;</a></span></dt>
<dd><p>Enable Hardware-assisted AddressSanitizer for compilation of the Linux kernel.
Similar to <samp class="option">-fsanitize=kernel-address</samp> but using an alternate
instrumentation method, and similar to <samp class="option">-fsanitize=hwaddress</samp> but with
instrumentation differences necessary for compiling the Linux kernel.
These differences are to avoid hwasan library initialization calls and to
account for the stack pointer having a different value in its top byte.
</p>
<p><em class="emph">Note:</em> This option has different defaults to the <samp class="option">-fsanitize=hwaddress</samp>.
Instrumenting the stack and alloca calls are not on by default but are still
possible by specifying the command-line options
<samp class="option">--param hwasan-instrument-stack=1</samp> and
<samp class="option">--param hwasan-instrument-allocas=1</samp> respectively. Using a random frame
tag is not implemented for kernel instrumentation.
</p>
</dd>
<dt><a id="index-fsanitize_003dpointer_002dcompare"></a><span><code class="code">-fsanitize=pointer-compare</code><a class="copiable-link" href="#index-fsanitize_003dpointer_002dcompare"> &para;</a></span></dt>
<dd><p>Instrument comparison operation (&lt;, &lt;=, &gt;, &gt;=) with pointer operands.
The option must be combined with either <samp class="option">-fsanitize=kernel-address</samp> or
<samp class="option">-fsanitize=address</samp>
The option cannot be combined with <samp class="option">-fsanitize=thread</samp>.
Note: By default the check is disabled at run time.  To enable it,
add <code class="code">detect_invalid_pointer_pairs=2</code> to the environment variable
<code class="env">ASAN_OPTIONS</code>. Using <code class="code">detect_invalid_pointer_pairs=1</code> detects
invalid operation only when both pointers are non-null.
</p>
</dd>
<dt><a id="index-fsanitize_003dpointer_002dsubtract"></a><span><code class="code">-fsanitize=pointer-subtract</code><a class="copiable-link" href="#index-fsanitize_003dpointer_002dsubtract"> &para;</a></span></dt>
<dd><p>Instrument subtraction with pointer operands.
The option must be combined with either <samp class="option">-fsanitize=kernel-address</samp> or
<samp class="option">-fsanitize=address</samp>
The option cannot be combined with <samp class="option">-fsanitize=thread</samp>.
Note: By default the check is disabled at run time.  To enable it,
add <code class="code">detect_invalid_pointer_pairs=2</code> to the environment variable
<code class="env">ASAN_OPTIONS</code>. Using <code class="code">detect_invalid_pointer_pairs=1</code> detects
invalid operation only when both pointers are non-null.
</p>
</dd>
<dt><a id="index-fsanitize_003dshadow_002dcall_002dstack"></a><span><code class="code">-fsanitize=shadow-call-stack</code><a class="copiable-link" href="#index-fsanitize_003dshadow_002dcall_002dstack"> &para;</a></span></dt>
<dd><p>Enable ShadowCallStack, a security enhancement mechanism used to protect
programs against return address overwrites (e.g. stack buffer overflows.)
It works by saving a function&rsquo;s return address to a separately allocated
shadow call stack in the function prologue and restoring the return address
from the shadow call stack in the function epilogue.  Instrumentation only
occurs in functions that need to save the return address to the stack.
</p>
<p>Currently it only supports the aarch64 platform.  It is specifically
designed for linux kernels that enable the CONFIG_SHADOW_CALL_STACK option.
For the user space programs, runtime support is not currently provided
in libc and libgcc.  Users who want to use this feature in user space need
to provide their own support for the runtime.  It should be noted that
this may cause the ABI rules to be broken.
</p>
<p>On aarch64, the instrumentation makes use of the platform register <code class="code">x18</code>.
This generally means that any code that may run on the same thread as code
compiled with ShadowCallStack must be compiled with the flag
<samp class="option">-ffixed-x18</samp>, otherwise functions compiled without
<samp class="option">-ffixed-x18</samp> might clobber <code class="code">x18</code> and so corrupt the shadow
stack pointer.
</p>
<p>Also, because there is no userspace runtime support, code compiled with
ShadowCallStack cannot use exception handling.  Use <samp class="option">-fno-exceptions</samp>
to turn off exceptions.
</p>
<p>See <a class="uref" href="https://clang.llvm.org/docs/ShadowCallStack.html">https://clang.llvm.org/docs/ShadowCallStack.html</a> for more
details.
</p>
</dd>
<dt><a id="index-fsanitize_003dthread"></a><span><code class="code">-fsanitize=thread</code><a class="copiable-link" href="#index-fsanitize_003dthread"> &para;</a></span></dt>
<dd><p>Enable ThreadSanitizer, a fast data race detector.
Memory access instructions are instrumented to detect
data race bugs.  See <a class="uref" href="https://github.com/google/sanitizers/wiki#threadsanitizer">https://github.com/google/sanitizers/wiki#threadsanitizer</a> for more
details. The run-time behavior can be influenced using the <code class="env">TSAN_OPTIONS</code>
environment variable; see
<a class="url" href="https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags">https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags</a> for a list of
supported options.
The option cannot be combined with <samp class="option">-fsanitize=address</samp>,
<samp class="option">-fsanitize=leak</samp>.
</p>
<p>Note that sanitized atomic builtins cannot throw exceptions when
operating on invalid memory addresses with non-call exceptions
(<samp class="option">-fnon-call-exceptions</samp>).
</p>
</dd>
<dt><a id="index-fsanitize_003dleak"></a><span><code class="code">-fsanitize=leak</code><a class="copiable-link" href="#index-fsanitize_003dleak"> &para;</a></span></dt>
<dd><p>Enable LeakSanitizer, a memory leak detector.
This option only matters for linking of executables.
The executable is linked against a library that overrides <code class="code">malloc</code>
and other allocator functions.  See
<a class="uref" href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer</a> for more
details.  The run-time behavior can be influenced using the
<code class="env">LSAN_OPTIONS</code> environment variable.
The option cannot be combined with <samp class="option">-fsanitize=thread</samp>.
</p>
</dd>
<dt><a id="index-fsanitize_003dundefined"></a><span><code class="code">-fsanitize=undefined</code><a class="copiable-link" href="#index-fsanitize_003dundefined"> &para;</a></span></dt>
<dd><p>Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
Various computations are instrumented to detect undefined behavior
at runtime.  See <a class="uref" href="https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html">https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html</a> for more details.   The run-time behavior can be influenced using the
<code class="env">UBSAN_OPTIONS</code> environment variable.  Current suboptions are:
</p>
<dl class="table">
<dt><a id="index-fsanitize_003dshift"></a><span><code class="code">-fsanitize=shift</code><a class="copiable-link" href="#index-fsanitize_003dshift"> &para;</a></span></dt>
<dd><p>This option enables checking that the result of a shift operation is
not undefined.  Note that what exactly is considered undefined differs
slightly between C and C++, as well as between ISO C90 and C99, etc.
This option has two suboptions, <samp class="option">-fsanitize=shift-base</samp> and
<samp class="option">-fsanitize=shift-exponent</samp>.
</p>
</dd>
<dt><a id="index-fsanitize_003dshift_002dexponent"></a><span><code class="code">-fsanitize=shift-exponent</code><a class="copiable-link" href="#index-fsanitize_003dshift_002dexponent"> &para;</a></span></dt>
<dd><p>This option enables checking that the second argument of a shift operation
is not negative and is smaller than the precision of the promoted first
argument.
</p>
</dd>
<dt><a id="index-fsanitize_003dshift_002dbase"></a><span><code class="code">-fsanitize=shift-base</code><a class="copiable-link" href="#index-fsanitize_003dshift_002dbase"> &para;</a></span></dt>
<dd><p>If the second argument of a shift operation is within range, check that the
result of a shift operation is not undefined.  Note that what exactly is
considered undefined differs slightly between C and C++, as well as between
ISO C90 and C99, etc.
</p>
</dd>
<dt><a id="index-fsanitize_003dinteger_002ddivide_002dby_002dzero"></a><span><code class="code">-fsanitize=integer-divide-by-zero</code><a class="copiable-link" href="#index-fsanitize_003dinteger_002ddivide_002dby_002dzero"> &para;</a></span></dt>
<dd><p>Detect integer division by zero.
</p>
</dd>
<dt><a id="index-fsanitize_003dunreachable"></a><span><code class="code">-fsanitize=unreachable</code><a class="copiable-link" href="#index-fsanitize_003dunreachable"> &para;</a></span></dt>
<dd><p>With this option, the compiler turns the <code class="code">__builtin_unreachable</code>
call into a diagnostics message call instead.  When reaching the
<code class="code">__builtin_unreachable</code> call, the behavior is undefined.
</p>
</dd>
<dt><a id="index-fsanitize_003dvla_002dbound"></a><span><code class="code">-fsanitize=vla-bound</code><a class="copiable-link" href="#index-fsanitize_003dvla_002dbound"> &para;</a></span></dt>
<dd><p>This option instructs the compiler to check that the size of a variable
length array is positive.
</p>
</dd>
<dt><a id="index-fsanitize_003dnull"></a><span><code class="code">-fsanitize=null</code><a class="copiable-link" href="#index-fsanitize_003dnull"> &para;</a></span></dt>
<dd><p>This option enables pointer checking.  Particularly, the application
built with this option turned on will issue an error message when it
tries to dereference a NULL pointer, or if a reference (possibly an
rvalue reference) is bound to a NULL pointer, or if a method is invoked
on an object pointed by a NULL pointer.
</p>
</dd>
<dt><a id="index-fsanitize_003dreturn"></a><span><code class="code">-fsanitize=return</code><a class="copiable-link" href="#index-fsanitize_003dreturn"> &para;</a></span></dt>
<dd><p>This option enables return statement checking.  Programs
built with this option turned on will issue an error message
when the end of a non-void function is reached without actually
returning a value.  This option works in C++ only.
</p>
</dd>
<dt><a id="index-fsanitize_003dsigned_002dinteger_002doverflow"></a><span><code class="code">-fsanitize=signed-integer-overflow</code><a class="copiable-link" href="#index-fsanitize_003dsigned_002dinteger_002doverflow"> &para;</a></span></dt>
<dd><p>This option enables signed integer overflow checking.  We check that
the result of <code class="code">+</code>, <code class="code">*</code>, and both unary and binary <code class="code">-</code>
does not overflow in the signed arithmetics.  This also detects
<code class="code">INT_MIN / -1</code> signed division.  Note, integer promotion
rules must be taken into account.  That is, the following is not an
overflow:
</p><div class="example smallexample">
<pre class="example-preformatted">signed char a = SCHAR_MAX;
a++;
</pre></div>

</dd>
<dt><a id="index-fsanitize_003dbounds"></a><span><code class="code">-fsanitize=bounds</code><a class="copiable-link" href="#index-fsanitize_003dbounds"> &para;</a></span></dt>
<dd><p>This option enables instrumentation of array bounds.  Various out of bounds
accesses are detected.  Flexible array members, flexible array member-like
arrays, and initializers of variables with static storage are not
instrumented, with the exception of flexible array member-like arrays
for which <code class="code">-fstrict-flex-arrays</code> or <code class="code">-fstrict-flex-arrays=</code>
options or <code class="code">strict_flex_array</code> attributes say they shouldn&rsquo;t be treated
like flexible array member-like arrays.
</p>
</dd>
<dt><a id="index-fsanitize_003dbounds_002dstrict"></a><span><code class="code">-fsanitize=bounds-strict</code><a class="copiable-link" href="#index-fsanitize_003dbounds_002dstrict"> &para;</a></span></dt>
<dd><p>This option enables strict instrumentation of array bounds.  Most out of bounds
accesses are detected, including flexible array member-like arrays.
Initializers of variables with static storage are not instrumented.
</p>
</dd>
<dt><a id="index-fsanitize_003dalignment"></a><span><code class="code">-fsanitize=alignment</code><a class="copiable-link" href="#index-fsanitize_003dalignment"> &para;</a></span></dt>
<dd>
<p>This option enables checking of alignment of pointers when they are
dereferenced, or when a reference is bound to insufficiently aligned target,
or when a method or constructor is invoked on insufficiently aligned object.
</p>
</dd>
<dt><a id="index-fsanitize_003dobject_002dsize"></a><span><code class="code">-fsanitize=object-size</code><a class="copiable-link" href="#index-fsanitize_003dobject_002dsize"> &para;</a></span></dt>
<dd><p>This option enables instrumentation of memory references using the
<code class="code">__builtin_dynamic_object_size</code> function.  Various out of bounds
pointer accesses are detected.
</p>
</dd>
<dt><a id="index-fsanitize_003dfloat_002ddivide_002dby_002dzero"></a><span><code class="code">-fsanitize=float-divide-by-zero</code><a class="copiable-link" href="#index-fsanitize_003dfloat_002ddivide_002dby_002dzero"> &para;</a></span></dt>
<dd><p>Detect floating-point division by zero.  Unlike other similar options,
<samp class="option">-fsanitize=float-divide-by-zero</samp> is not enabled by
<samp class="option">-fsanitize=undefined</samp>, since floating-point division by zero can
be a legitimate way of obtaining infinities and NaNs.
</p>
</dd>
<dt><a id="index-fsanitize_003dfloat_002dcast_002doverflow"></a><span><code class="code">-fsanitize=float-cast-overflow</code><a class="copiable-link" href="#index-fsanitize_003dfloat_002dcast_002doverflow"> &para;</a></span></dt>
<dd><p>This option enables floating-point type to integer conversion checking.
We check that the result of the conversion does not overflow.
Unlike other similar options, <samp class="option">-fsanitize=float-cast-overflow</samp> is
not enabled by <samp class="option">-fsanitize=undefined</samp>.
This option does not work well with <code class="code">FE_INVALID</code> exceptions enabled.
</p>
</dd>
<dt><a id="index-fsanitize_003dnonnull_002dattribute"></a><span><code class="code">-fsanitize=nonnull-attribute</code><a class="copiable-link" href="#index-fsanitize_003dnonnull_002dattribute"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of calls, checking whether null values
are not passed to arguments marked as requiring a non-null value by the
<code class="code">nonnull</code> function attribute.
</p>
</dd>
<dt><a id="index-fsanitize_003dreturns_002dnonnull_002dattribute"></a><span><code class="code">-fsanitize=returns-nonnull-attribute</code><a class="copiable-link" href="#index-fsanitize_003dreturns_002dnonnull_002dattribute"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of return statements in functions
marked with <code class="code">returns_nonnull</code> function attribute, to detect returning
of null values from such functions.
</p>
</dd>
<dt><a id="index-fsanitize_003dbool"></a><span><code class="code">-fsanitize=bool</code><a class="copiable-link" href="#index-fsanitize_003dbool"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of loads from bool.  If a value other
than 0/1 is loaded, a run-time error is issued.
</p>
</dd>
<dt><a id="index-fsanitize_003denum"></a><span><code class="code">-fsanitize=enum</code><a class="copiable-link" href="#index-fsanitize_003denum"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of loads from an enum type.  If
a value outside the range of values for the enum type is loaded,
a run-time error is issued.
</p>
</dd>
<dt><a id="index-fsanitize_003dvptr"></a><span><code class="code">-fsanitize=vptr</code><a class="copiable-link" href="#index-fsanitize_003dvptr"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of C++ member function calls, member
accesses and some conversions between pointers to base and derived classes,
to verify the referenced object has the correct dynamic type.
</p>
</dd>
<dt><a id="index-fsanitize_003dpointer_002doverflow"></a><span><code class="code">-fsanitize=pointer-overflow</code><a class="copiable-link" href="#index-fsanitize_003dpointer_002doverflow"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of pointer arithmetics.  If the pointer
arithmetics overflows, a run-time error is issued.
</p>
</dd>
<dt><a id="index-fsanitize_003dbuiltin"></a><span><code class="code">-fsanitize=builtin</code><a class="copiable-link" href="#index-fsanitize_003dbuiltin"> &para;</a></span></dt>
<dd>
<p>This option enables instrumentation of arguments to selected builtin
functions.  If an invalid value is passed to such arguments, a run-time
error is issued.  E.g.&nbsp;passing 0 as the argument to <code class="code">__builtin_ctz</code>
or <code class="code">__builtin_clz</code> invokes undefined behavior and is diagnosed
by this option.
</p>
</dd>
</dl>

<p>Note that sanitizers tend to increase the rate of false positive
warnings, most notably those around <samp class="option">-Wmaybe-uninitialized</samp>.
We recommend against combining <samp class="option">-Werror</samp> and [the use of]
sanitizers.
</p>
<p>While <samp class="option">-ftrapv</samp> causes traps for signed overflows to be emitted,
<samp class="option">-fsanitize=undefined</samp> gives a diagnostic message.
This currently works only for the C family of languages.
</p>
</dd>
<dt><a id="index-fno_002dsanitize_003dall"></a><span><code class="code">-fno-sanitize=all</code><a class="copiable-link" href="#index-fno_002dsanitize_003dall"> &para;</a></span></dt>
<dd>
<p>This option disables all previously enabled sanitizers.
<samp class="option">-fsanitize=all</samp> is not allowed, as some sanitizers cannot be used
together.
</p>
</dd>
<dt><a id="index-fasan_002dshadow_002doffset"></a><span><code class="code">-fasan-shadow-offset=<var class="var">number</var></code><a class="copiable-link" href="#index-fasan_002dshadow_002doffset"> &para;</a></span></dt>
<dd><p>This option forces GCC to use custom shadow offset in AddressSanitizer checks.
It is useful for experimenting with different shadow memory layouts in
Kernel AddressSanitizer.
</p>
</dd>
<dt><a id="index-fsanitize_002dsections"></a><span><code class="code">-fsanitize-sections=<var class="var">s1</var>,<var class="var">s2</var>,...</code><a class="copiable-link" href="#index-fsanitize_002dsections"> &para;</a></span></dt>
<dd><p>Sanitize global variables in selected user-defined sections.  <var class="var">si</var> may
contain wildcards.
</p>
</dd>
<dt><a class="index-entry-id" id="index-fno_002dsanitize_002drecover"></a>
<a id="index-fsanitize_002drecover"></a><span><code class="code">-fsanitize-recover<span class="r">[</span>=<var class="var">opts</var><span class="r">]</span></code><a class="copiable-link" href="#index-fsanitize_002drecover"> &para;</a></span></dt>
<dd><p><samp class="option">-fsanitize-recover=</samp> controls error recovery mode for sanitizers
mentioned in comma-separated list of <var class="var">opts</var>.  Enabling this option
for a sanitizer component causes it to attempt to continue
running the program as if no error happened.  This means multiple
runtime errors can be reported in a single program run, and the exit
code of the program may indicate success even when errors
have been reported.  The <samp class="option">-fno-sanitize-recover=</samp> option
can be used to alter
this behavior: only the first detected error is reported
and program then exits with a non-zero exit code.
</p>
<p>Currently this feature only works for <samp class="option">-fsanitize=undefined</samp> (and its suboptions
except for <samp class="option">-fsanitize=unreachable</samp> and <samp class="option">-fsanitize=return</samp>),
<samp class="option">-fsanitize=float-cast-overflow</samp>, <samp class="option">-fsanitize=float-divide-by-zero</samp>,
<samp class="option">-fsanitize=bounds-strict</samp>,
<samp class="option">-fsanitize=kernel-address</samp> and <samp class="option">-fsanitize=address</samp>.
For these sanitizers error recovery is turned on by default,
except <samp class="option">-fsanitize=address</samp>, for which this feature is experimental.
<samp class="option">-fsanitize-recover=all</samp> and <samp class="option">-fno-sanitize-recover=all</samp> is also
accepted, the former enables recovery for all sanitizers that support it,
the latter disables recovery for all sanitizers that support it.
</p>
<p>Even if a recovery mode is turned on the compiler side, it needs to be also
enabled on the runtime library side, otherwise the failures are still fatal.
The runtime library defaults to <code class="code">halt_on_error=0</code> for
ThreadSanitizer and UndefinedBehaviorSanitizer, while default value for
AddressSanitizer is <code class="code">halt_on_error=1</code>. This can be overridden through
setting the <code class="code">halt_on_error</code> flag in the corresponding environment variable.
</p>
<p>Syntax without an explicit <var class="var">opts</var> parameter is deprecated.  It is
equivalent to specifying an <var class="var">opts</var> list of:
</p>
<div class="example smallexample">
<pre class="example-preformatted">undefined,float-cast-overflow,float-divide-by-zero,bounds-strict
</pre></div>

</dd>
<dt><a id="index-fsanitize_002daddress_002duse_002dafter_002dscope"></a><span><code class="code">-fsanitize-address-use-after-scope</code><a class="copiable-link" href="#index-fsanitize_002daddress_002duse_002dafter_002dscope"> &para;</a></span></dt>
<dd><p>Enable sanitization of local variables to detect use-after-scope bugs.
The option sets <samp class="option">-fstack-reuse</samp> to &lsquo;<samp class="samp">none</samp>&rsquo;.
</p>
</dd>
<dt><a class="index-entry-id" id="index-fno_002dsanitize_002dtrap"></a>
<a id="index-fsanitize_002dtrap"></a><span><code class="code">-fsanitize-trap<span class="r">[</span>=<var class="var">opts</var><span class="r">]</span></code><a class="copiable-link" href="#index-fsanitize_002dtrap"> &para;</a></span></dt>
<dd><p>The <samp class="option">-fsanitize-trap=</samp> option instructs the compiler to
report for sanitizers mentioned in comma-separated list of <var class="var">opts</var>
undefined behavior using <code class="code">__builtin_trap</code> rather than a <code class="code">libubsan</code>
library routine.  If this option is enabled for certain sanitizer,
it takes precedence over the <samp class="option">-fsanitizer-recover=</samp> for that
sanitizer, <code class="code">__builtin_trap</code> will be emitted and be fatal regardless
of whether recovery is enabled or disabled using <samp class="option">-fsanitize-recover=</samp>.
</p>
<p>The advantage of this is that the <code class="code">libubsan</code> library is not needed
and is not linked in, so this is usable even in freestanding environments.
</p>
<p>Currently this feature works with <samp class="option">-fsanitize=undefined</samp> (and its suboptions
except for <samp class="option">-fsanitize=vptr</samp>), <samp class="option">-fsanitize=float-cast-overflow</samp>,
<samp class="option">-fsanitize=float-divide-by-zero</samp> and
<samp class="option">-fsanitize=bounds-strict</samp>.  <code class="code">-fsanitize-trap=all</code> can be also
specified, which enables it for <code class="code">undefined</code> suboptions,
<samp class="option">-fsanitize=float-cast-overflow</samp>,
<samp class="option">-fsanitize=float-divide-by-zero</samp> and
<samp class="option">-fsanitize=bounds-strict</samp>.
If <code class="code">-fsanitize-trap=undefined</code> or <code class="code">-fsanitize-trap=all</code> is used
and <code class="code">-fsanitize=vptr</code> is enabled on the command line, the
instrumentation is silently ignored as the instrumentation always needs
<code class="code">libubsan</code> support, <samp class="option">-fsanitize-trap=vptr</samp> is not allowed.
</p>
</dd>
<dt><a id="index-fsanitize_002dundefined_002dtrap_002don_002derror"></a><span><code class="code">-fsanitize-undefined-trap-on-error</code><a class="copiable-link" href="#index-fsanitize_002dundefined_002dtrap_002don_002derror"> &para;</a></span></dt>
<dd><p>The <samp class="option">-fsanitize-undefined-trap-on-error</samp> option is deprecated
equivalent of <samp class="option">-fsanitize-trap=all</samp>.
</p>
</dd>
<dt><a id="index-fsanitize_002dcoverage_003dtrace_002dpc"></a><span><code class="code">-fsanitize-coverage=trace-pc</code><a class="copiable-link" href="#index-fsanitize_002dcoverage_003dtrace_002dpc"> &para;</a></span></dt>
<dd><p>Enable coverage-guided fuzzing code instrumentation.
Inserts a call to <code class="code">__sanitizer_cov_trace_pc</code> into every basic block.
</p>
</dd>
<dt><a id="index-fsanitize_002dcoverage_003dtrace_002dcmp"></a><span><code class="code">-fsanitize-coverage=trace-cmp</code><a class="copiable-link" href="#index-fsanitize_002dcoverage_003dtrace_002dcmp"> &para;</a></span></dt>
<dd><p>Enable dataflow guided fuzzing code instrumentation.
Inserts a call to <code class="code">__sanitizer_cov_trace_cmp1</code>,
<code class="code">__sanitizer_cov_trace_cmp2</code>, <code class="code">__sanitizer_cov_trace_cmp4</code> or
<code class="code">__sanitizer_cov_trace_cmp8</code> for integral comparison with both operands
variable or <code class="code">__sanitizer_cov_trace_const_cmp1</code>,
<code class="code">__sanitizer_cov_trace_const_cmp2</code>,
<code class="code">__sanitizer_cov_trace_const_cmp4</code> or
<code class="code">__sanitizer_cov_trace_const_cmp8</code> for integral comparison with one
operand constant, <code class="code">__sanitizer_cov_trace_cmpf</code> or
<code class="code">__sanitizer_cov_trace_cmpd</code> for float or double comparisons and
<code class="code">__sanitizer_cov_trace_switch</code> for switch statements.
</p>
</dd>
<dt><a id="index-fcf_002dprotection"></a><span><code class="code">-fcf-protection=<span class="r">[</span>full<span class="r">|</span>branch<span class="r">|</span>return<span class="r">|</span>none<span class="r">|</span>check<span class="r">]</span></code><a class="copiable-link" href="#index-fcf_002dprotection"> &para;</a></span></dt>
<dd><p>Enable code instrumentation of control-flow transfers to increase
program security by checking that target addresses of control-flow
transfer instructions (such as indirect function call, function return,
indirect jump) are valid.  This prevents diverting the flow of control
to an unexpected target.  This is intended to protect against such
threats as Return-oriented Programming (ROP), and similarly
call/jmp-oriented programming (COP/JOP).
</p>
<p>The value <code class="code">branch</code> tells the compiler to implement checking of
validity of control-flow transfer at the point of indirect branch
instructions, i.e. call/jmp instructions.  The value <code class="code">return</code>
implements checking of validity at the point of returning from a
function.  The value <code class="code">full</code> is an alias for specifying both
<code class="code">branch</code> and <code class="code">return</code>. The value <code class="code">none</code> turns off
instrumentation.
</p>
<p>The value <code class="code">check</code> is used for the final link with link-time
optimization (LTO).  An error is issued if LTO object files are
compiled with different <samp class="option">-fcf-protection</samp> values.  The
value <code class="code">check</code> is ignored at the compile time.
</p>
<p>The macro <code class="code">__CET__</code> is defined when <samp class="option">-fcf-protection</samp> is
used.  The first bit of <code class="code">__CET__</code> is set to 1 for the value
<code class="code">branch</code> and the second bit of <code class="code">__CET__</code> is set to 1 for
the <code class="code">return</code>.
</p>
<p>You can also use the <code class="code">nocf_check</code> attribute to identify
which functions and calls should be skipped from instrumentation
(see <a class="pxref" href="Function-Attributes.html">Declaring Attributes of Functions</a>).
</p>
<p>Currently the x86 GNU/Linux target provides an implementation based
on Intel Control-flow Enforcement Technology (CET) which works for
i686 processor or newer.
</p>
</dd>
<dt><a id="index-fharden_002dcompares"></a><span><code class="code">-fharden-compares</code><a class="copiable-link" href="#index-fharden_002dcompares"> &para;</a></span></dt>
<dd><p>For every logical test that survives gimple optimizations and is
<em class="emph">not</em> the condition in a conditional branch (for example,
conditions tested for conditional moves, or to store in boolean
variables), emit extra code to compute and verify the reversed
condition, and to call <code class="code">__builtin_trap</code> if the results do not
match.  Use with &lsquo;<samp class="samp">-fharden-conditional-branches</samp>&rsquo; to cover all
conditionals.
</p>
</dd>
<dt><a id="index-fharden_002dconditional_002dbranches"></a><span><code class="code">-fharden-conditional-branches</code><a class="copiable-link" href="#index-fharden_002dconditional_002dbranches"> &para;</a></span></dt>
<dd><p>For every non-vectorized conditional branch that survives gimple
optimizations, emit extra code to compute and verify the reversed
condition, and to call <code class="code">__builtin_trap</code> if the result is
unexpected.  Use with &lsquo;<samp class="samp">-fharden-compares</samp>&rsquo; to cover all
conditionals.
</p>
</dd>
<dt><a id="index-fstack_002dprotector"></a><span><code class="code">-fstack-protector</code><a class="copiable-link" href="#index-fstack_002dprotector"> &para;</a></span></dt>
<dd><p>Emit extra code to check for buffer overflows, such as stack smashing
attacks.  This is done by adding a guard variable to functions with
vulnerable objects.  This includes functions that call <code class="code">alloca</code>, and
functions with buffers larger than or equal to 8 bytes.  The guards are
initialized when a function is entered and then checked when the function
exits.  If a guard check fails, an error message is printed and the program
exits.  Only variables that are actually allocated on the stack are
considered, optimized away variables or variables allocated in registers
don&rsquo;t count.
</p>
</dd>
<dt><a id="index-fstack_002dprotector_002dall"></a><span><code class="code">-fstack-protector-all</code><a class="copiable-link" href="#index-fstack_002dprotector_002dall"> &para;</a></span></dt>
<dd><p>Like <samp class="option">-fstack-protector</samp> except that all functions are protected.
</p>
</dd>
<dt><a id="index-fstack_002dprotector_002dstrong"></a><span><code class="code">-fstack-protector-strong</code><a class="copiable-link" href="#index-fstack_002dprotector_002dstrong"> &para;</a></span></dt>
<dd><p>Like <samp class="option">-fstack-protector</samp> but includes additional functions to
be protected &mdash; those that have local array definitions, or have
references to local frame addresses.  Only variables that are actually
allocated on the stack are considered, optimized away variables or variables
allocated in registers don&rsquo;t count.
</p>
</dd>
<dt><a id="index-fstack_002dprotector_002dexplicit"></a><span><code class="code">-fstack-protector-explicit</code><a class="copiable-link" href="#index-fstack_002dprotector_002dexplicit"> &para;</a></span></dt>
<dd><p>Like <samp class="option">-fstack-protector</samp> but only protects those functions which
have the <code class="code">stack_protect</code> attribute.
</p>
</dd>
<dt><a id="index-fstack_002dcheck"></a><span><code class="code">-fstack-check</code><a class="copiable-link" href="#index-fstack_002dcheck"> &para;</a></span></dt>
<dd><p>Generate code to verify that you do not go beyond the boundary of the
stack.  You should specify this flag if you are running in an
environment with multiple threads, but you only rarely need to specify it in
a single-threaded environment since stack overflow is automatically
detected on nearly all systems if there is only one stack.
</p>
<p>Note that this switch does not actually cause checking to be done; the
operating system or the language runtime must do that.  The switch causes
generation of code to ensure that they see the stack being extended.
</p>
<p>You can additionally specify a string parameter: &lsquo;<samp class="samp">no</samp>&rsquo; means no
checking, &lsquo;<samp class="samp">generic</samp>&rsquo; means force the use of old-style checking,
&lsquo;<samp class="samp">specific</samp>&rsquo; means use the best checking method and is equivalent
to bare <samp class="option">-fstack-check</samp>.
</p>
<p>Old-style checking is a generic mechanism that requires no specific
target support in the compiler but comes with the following drawbacks:
</p>
<ol class="enumerate">
<li> Modified allocation strategy for large objects: they are always
allocated dynamically if their size exceeds a fixed threshold.  Note this
may change the semantics of some code.

</li><li> Fixed limit on the size of the static frame of functions: when it is
topped by a particular function, stack checking is not reliable and
a warning is issued by the compiler.

</li><li> Inefficiency: because of both the modified allocation strategy and the
generic implementation, code performance is hampered.
</li></ol>

<p>Note that old-style stack checking is also the fallback method for
&lsquo;<samp class="samp">specific</samp>&rsquo; if no target support has been added in the compiler.
</p>
<p>&lsquo;<samp class="samp">-fstack-check=</samp>&rsquo; is designed for Ada&rsquo;s needs to detect infinite recursion
and stack overflows.  &lsquo;<samp class="samp">specific</samp>&rsquo; is an excellent choice when compiling
Ada code.  It is not generally sufficient to protect against stack-clash
attacks.  To protect against those you want &lsquo;<samp class="samp">-fstack-clash-protection</samp>&rsquo;.
</p>
</dd>
<dt><a id="index-fstack_002dclash_002dprotection"></a><span><code class="code">-fstack-clash-protection</code><a class="copiable-link" href="#index-fstack_002dclash_002dprotection"> &para;</a></span></dt>
<dd><p>Generate code to prevent stack clash style attacks.  When this option is
enabled, the compiler will only allocate one page of stack space at a time
and each page is accessed immediately after allocation.  Thus, it prevents
allocations from jumping over any stack guard page provided by the
operating system.
</p>
<p>Most targets do not fully support stack clash protection.  However, on
those targets <samp class="option">-fstack-clash-protection</samp> will protect dynamic stack
allocations.  <samp class="option">-fstack-clash-protection</samp> may also provide limited
protection for static stack allocations if the target supports
<samp class="option">-fstack-check=specific</samp>.
</p>
</dd>
<dt><a class="index-entry-id" id="index-fstack_002dlimit_002dsymbol"></a>
<a class="index-entry-id" id="index-fno_002dstack_002dlimit"></a>
<a id="index-fstack_002dlimit_002dregister"></a><span><code class="code">-fstack-limit-register=<var class="var">reg</var></code><a class="copiable-link" href="#index-fstack_002dlimit_002dregister"> &para;</a></span></dt>
<dt><code class="code">-fstack-limit-symbol=<var class="var">sym</var></code></dt>
<dt><code class="code">-fno-stack-limit</code></dt>
<dd><p>Generate code to ensure that the stack does not grow beyond a certain value,
either the value of a register or the address of a symbol.  If a larger
stack is required, a signal is raised at run time.  For most targets,
the signal is raised before the stack overruns the boundary, so
it is possible to catch the signal without taking special precautions.
</p>
<p>For instance, if the stack starts at absolute address &lsquo;<samp class="samp">0x80000000</samp>&rsquo;
and grows downwards, you can use the flags
<samp class="option">-fstack-limit-symbol=__stack_limit</samp> and
<samp class="option">-Wl,--defsym,__stack_limit=0x7ffe0000</samp> to enforce a stack limit
of 128KB.  Note that this may only work with the GNU linker.
</p>
<p>You can locally override stack limit checking by using the
<code class="code">no_stack_limit</code> function attribute (see <a class="pxref" href="Function-Attributes.html">Declaring Attributes of Functions</a>).
</p>
</dd>
<dt><a id="index-fsplit_002dstack"></a><span><code class="code">-fsplit-stack</code><a class="copiable-link" href="#index-fsplit_002dstack"> &para;</a></span></dt>
<dd><p>Generate code to automatically split the stack before it overflows.
The resulting program has a discontiguous stack which can only
overflow if the program is unable to allocate any more memory.  This
is most useful when running threaded programs, as it is no longer
necessary to calculate a good stack size to use for each thread.  This
is currently only implemented for the x86 targets running
GNU/Linux.
</p>
<p>When code compiled with <samp class="option">-fsplit-stack</samp> calls code compiled
without <samp class="option">-fsplit-stack</samp>, there may not be much stack space
available for the latter code to run.  If compiling all code,
including library code, with <samp class="option">-fsplit-stack</samp> is not an option,
then the linker can fix up these calls so that the code compiled
without <samp class="option">-fsplit-stack</samp> always has a large stack.  Support for
this is implemented in the gold linker in GNU binutils release 2.21
and later.
</p>
</dd>
<dt><a id="index-fvtable_002dverify"></a><span><code class="code">-fvtable-verify=<span class="r">[</span>std<span class="r">|</span>preinit<span class="r">|</span>none<span class="r">]</span></code><a class="copiable-link" href="#index-fvtable_002dverify"> &para;</a></span></dt>
<dd><p>This option is only available when compiling C++ code.
It turns on (or off, if using <samp class="option">-fvtable-verify=none</samp>) the security
feature that verifies at run time, for every virtual call, that
the vtable pointer through which the call is made is valid for the type of
the object, and has not been corrupted or overwritten.  If an invalid vtable
pointer is detected at run time, an error is reported and execution of the
program is immediately halted.
</p>
<p>This option causes run-time data structures to be built at program startup,
which are used for verifying the vtable pointers.  
The options &lsquo;<samp class="samp">std</samp>&rsquo; and &lsquo;<samp class="samp">preinit</samp>&rsquo;
control the timing of when these data structures are built.  In both cases the
data structures are built before execution reaches <code class="code">main</code>.  Using
<samp class="option">-fvtable-verify=std</samp> causes the data structures to be built after
shared libraries have been loaded and initialized.
<samp class="option">-fvtable-verify=preinit</samp> causes them to be built before shared
libraries have been loaded and initialized.
</p>
<p>If this option appears multiple times in the command line with different
values specified, &lsquo;<samp class="samp">none</samp>&rsquo; takes highest priority over both &lsquo;<samp class="samp">std</samp>&rsquo; and
&lsquo;<samp class="samp">preinit</samp>&rsquo;; &lsquo;<samp class="samp">preinit</samp>&rsquo; takes priority over &lsquo;<samp class="samp">std</samp>&rsquo;.
</p>
</dd>
<dt><a id="index-fvtv_002ddebug"></a><span><code class="code">-fvtv-debug</code><a class="copiable-link" href="#index-fvtv_002ddebug"> &para;</a></span></dt>
<dd><p>When used in conjunction with <samp class="option">-fvtable-verify=std</samp> or 
<samp class="option">-fvtable-verify=preinit</samp>, causes debug versions of the 
runtime functions for the vtable verification feature to be called.  
This flag also causes the compiler to log information about which 
vtable pointers it finds for each class.
This information is written to a file named <samp class="file">vtv_set_ptr_data.log</samp> 
in the directory named by the environment variable <code class="env">VTV_LOGS_DIR</code> 
if that is defined or the current working directory otherwise.
</p>
<p>Note:  This feature <em class="emph">appends</em> data to the log file. If you want a fresh log
file, be sure to delete any existing one.
</p>
</dd>
<dt><a id="index-fvtv_002dcounts"></a><span><code class="code">-fvtv-counts</code><a class="copiable-link" href="#index-fvtv_002dcounts"> &para;</a></span></dt>
<dd><p>This is a debugging flag.  When used in conjunction with
<samp class="option">-fvtable-verify=std</samp> or <samp class="option">-fvtable-verify=preinit</samp>, this
causes the compiler to keep track of the total number of virtual calls
it encounters and the number of verifications it inserts.  It also
counts the number of calls to certain run-time library functions
that it inserts and logs this information for each compilation unit.
The compiler writes this information to a file named
<samp class="file">vtv_count_data.log</samp> in the directory named by the environment
variable <code class="env">VTV_LOGS_DIR</code> if that is defined or the current working
directory otherwise.  It also counts the size of the vtable pointer sets
for each class, and writes this information to <samp class="file">vtv_class_set_sizes.log</samp>
in the same directory.
</p>
<p>Note:  This feature <em class="emph">appends</em> data to the log files.  To get fresh log
files, be sure to delete any existing ones.
</p>
</dd>
<dt><a id="index-finstrument_002dfunctions"></a><span><code class="code">-finstrument-functions</code><a class="copiable-link" href="#index-finstrument_002dfunctions"> &para;</a></span></dt>
<dd><p>Generate instrumentation calls for entry and exit to functions.  Just
after function entry and just before function exit, the following
profiling functions are called with the address of the current
function and its call site.  (On some platforms,
<code class="code">__builtin_return_address</code> does not work beyond the current
function, so the call site information may not be available to the
profiling functions otherwise.)
</p>
<div class="example smallexample">
<pre class="example-preformatted">void __cyg_profile_func_enter (void *this_fn,
                               void *call_site);
void __cyg_profile_func_exit  (void *this_fn,
                               void *call_site);
</pre></div>

<p>The first argument is the address of the start of the current function,
which may be looked up exactly in the symbol table.
</p>
<p>This instrumentation is also done for functions expanded inline in other
functions.  The profiling calls indicate where, conceptually, the
inline function is entered and exited.  This means that addressable
versions of such functions must be available.  If all your uses of a
function are expanded inline, this may mean an additional expansion of
code size.  If you use <code class="code">extern inline</code> in your C code, an
addressable version of such functions must be provided.  (This is
normally the case anyway, but if you get lucky and the optimizer always
expands the functions inline, you might have gotten away without
providing static copies.)
</p>
<p>A function may be given the attribute <code class="code">no_instrument_function</code>, in
which case this instrumentation is not done.  This can be used, for
example, for the profiling functions listed above, high-priority
interrupt routines, and any functions from which the profiling functions
cannot safely be called (perhaps signal handlers, if the profiling
routines generate output or allocate memory).
See <a class="xref" href="Common-Function-Attributes.html">Common Function Attributes</a>.
</p>
</dd>
<dt><a id="index-finstrument_002dfunctions_002donce"></a><span><code class="code">-finstrument-functions-once</code><a class="copiable-link" href="#index-finstrument_002dfunctions_002donce"> &para;</a></span></dt>
<dd><p>This is similar to <samp class="option">-finstrument-functions</samp>, but the profiling
functions are called only once per instrumented function, i.e. the first
profiling function is called after the first entry into the instrumented
function and the second profiling function is called before the exit
corresponding to this first entry.
</p>
<p>The definition of <code class="code">once</code> for the purpose of this option is a little
vague because the implementation is not protected against data races.
As a result, the implementation only guarantees that the profiling
functions are called at <em class="emph">least</em> once per process and at <em class="emph">most</em>
once per thread, but the calls are always paired, that is to say, if a
thread calls the first function, then it will call the second function,
unless it never reaches the exit of the instrumented function.
</p>
</dd>
<dt><a id="index-finstrument_002dfunctions_002dexclude_002dfile_002dlist"></a><span><code class="code">-finstrument-functions-exclude-file-list=<var class="var">file</var>,<var class="var">file</var>,&hellip;</code><a class="copiable-link" href="#index-finstrument_002dfunctions_002dexclude_002dfile_002dlist"> &para;</a></span></dt>
<dd>
<p>Set the list of functions that are excluded from instrumentation (see
the description of <samp class="option">-finstrument-functions</samp>).  If the file that
contains a function definition matches with one of <var class="var">file</var>, then
that function is not instrumented.  The match is done on substrings:
if the <var class="var">file</var> parameter is a substring of the file name, it is
considered to be a match.
</p>
<p>For example:
</p>
<div class="example smallexample">
<pre class="example-preformatted">-finstrument-functions-exclude-file-list=/bits/stl,include/sys
</pre></div>

<p>excludes any inline function defined in files whose pathnames
contain <samp class="file">/bits/stl</samp> or <samp class="file">include/sys</samp>.
</p>
<p>If, for some reason, you want to include letter &lsquo;<samp class="samp">,</samp>&rsquo; in one of
<var class="var">sym</var>, write &lsquo;<samp class="samp">\,</samp>&rsquo;. For example,
<samp class="option">-finstrument-functions-exclude-file-list='\,\,tmp'</samp>
(note the single quote surrounding the option).
</p>
</dd>
<dt><a id="index-finstrument_002dfunctions_002dexclude_002dfunction_002dlist"></a><span><code class="code">-finstrument-functions-exclude-function-list=<var class="var">sym</var>,<var class="var">sym</var>,&hellip;</code><a class="copiable-link" href="#index-finstrument_002dfunctions_002dexclude_002dfunction_002dlist"> &para;</a></span></dt>
<dd>
<p>This is similar to <samp class="option">-finstrument-functions-exclude-file-list</samp>,
but this option sets the list of function names to be excluded from
instrumentation.  The function name to be matched is its user-visible
name, such as <code class="code">vector&lt;int&gt; blah(const vector&lt;int&gt; &amp;)</code>, not the
internal mangled name (e.g., <code class="code">_Z4blahRSt6vectorIiSaIiEE</code>).  The
match is done on substrings: if the <var class="var">sym</var> parameter is a substring
of the function name, it is considered to be a match.  For C99 and C++
extended identifiers, the function name must be given in UTF-8, not
using universal character names.
</p>
</dd>
<dt><a id="index-fpatchable_002dfunction_002dentry"></a><span><code class="code">-fpatchable-function-entry=<var class="var">N</var>[,<var class="var">M</var>]</code><a class="copiable-link" href="#index-fpatchable_002dfunction_002dentry"> &para;</a></span></dt>
<dd><p>Generate <var class="var">N</var> NOPs right at the beginning
of each function, with the function entry point before the <var class="var">M</var>th NOP.
If <var class="var">M</var> is omitted, it defaults to <code class="code">0</code> so the
function entry points to the address just at the first NOP.
The NOP instructions reserve extra space which can be used to patch in
any desired instrumentation at run time, provided that the code segment
is writable.  The amount of space is controllable indirectly via
the number of NOPs; the NOP instruction used corresponds to the instruction
emitted by the internal GCC back-end interface <code class="code">gen_nop</code>.  This behavior
is target-specific and may also depend on the architecture variant and/or
other compilation options.
</p>
<p>For run-time identification, the starting addresses of these areas,
which correspond to their respective function entries minus <var class="var">M</var>,
are additionally collected in the <code class="code">__patchable_function_entries</code>
section of the resulting binary.
</p>
<p>Note that the value of <code class="code">__attribute__ ((patchable_function_entry
(N,M)))</code> takes precedence over command-line option
<samp class="option">-fpatchable-function-entry=N,M</samp>.  This can be used to increase
the area size or to remove it completely on a single function.
If <code class="code">N=0</code>, no pad location is recorded.
</p>
<p>The NOP instructions are inserted at&mdash;and maybe before, depending on
<var class="var">M</var>&mdash;the function entry address, even before the prologue.  On
PowerPC with the ELFv2 ABI, for a function with dual entry points,
the local entry point is this function entry address.
</p>
<p>The maximum value of <var class="var">N</var> and <var class="var">M</var> is 65535.  On PowerPC with the
ELFv2 ABI, for a function with dual entry points, the supported values
for <var class="var">M</var> are 0, 2, 6 and 14.
</p></dd>
</dl>


</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Preprocessor-Options.html">Options Controlling the Preprocessor</a>, Previous: <a href="Optimize-Options.html">Options That Control Optimization</a>, Up: <a href="Invoking-GCC.html">GCC Command Options</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
